Skip to content

Resolve fuzzy entries in dataclasses/faq-library and improve translation skills - #1250

Draft
josix wants to merge 6 commits into
python:3.15from
josix:fix/fuzzy-dataclasses-faq-library
Draft

josix wants to merge 6 commits into
python:3.15from
josix:fix/fuzzy-dataclasses-faq-library

Conversation

@josix

@josix josix commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator

背景

library/dataclasses.po 與 faq/library.po 共有 145 條 fuzzy 條目(94 + 51)。這些譯文多半是舊的機器翻譯,原文更新後已經對不上:有些只翻了一部分(例如 *unsafe_hash*),有些 reST role 寫壞了(例如 :meth: \!init``),也有不通順的句子(例如「方法將是產生」)。

fuzzy 條目在 translations.python.org 的進度計算中算作未翻譯,這兩個檔案合計約 5,000 個英文字,大約是整體進度的 0.28 個百分點。

變更內容

1. 修正 fuzzy 條目(ae5803ed8c)

  • 依據目前的 msgid 重新翻譯全部 145 條,並移除 fuzzy 標記
  • 只替換 msgstr,msgid 一行都沒動;msgfmt -c 通過
  • 用 translation memory(見下一項)比對 repo 中既有的譯法,確認用詞一致:
英文 譯法 既有用例
keyword-only 僅限關鍵字 tutorial/controlflow.po、whatsnew/3.10.po
sentinel 哨兵 library/unittest.mock.po
shallow copy 淺複製 library/collections.po、tutorial/datastructures.po
weak reference 弱參照 c-api/weakref.po、library/exceptions.po
default factory 預設工廠函式 library/dataclasses.po
mutex 互斥鎖 library/asyncio-sync.po
generate 產生 全 repo「產生」549 次 vs「生成」158 次;dataclasses.po 內已統一

需要 reviewer 留意的用詞:

  • semaphore:asyncio 文件用「旗號」,_thread 與 tutorial 用「號誌」。faq/library.po 這段在講執行緒,所以沿用「號誌」。
  • atomic:glossary.po 的 atomic operation 尚未翻譯,repo 內「原子性」和「不可分割」都有人用。這裡用「不可分割的(atomic)」。

2. 在 Claude skills 中加入 translation memory 查詢(1b4d6bf533)

  • 新增 .scripts/translation_memory.sh 與 .scripts/translation_memory/main.py(只用標準函式庫)。它透過 agentic-retrieval 為 repo 內的 .po 建立索引,並回傳已翻譯、非 fuzzy 的相似條目(msgid/msgstr 對照與 path:line)
  • translate-po、check-terminology、validate-translation 三個 skill 加入查詢步驟。查到的結果只作為參考,glossary.po 和 README 的規則優先;找不到 engine 時會直接跳過
  • README 說明安裝與用法;CLAUDE.md 加上入口連結;索引目錄 .agentic-retrieval/ 已加入 gitignore

第 1 項的用詞檢查就是用這個工具完成的。

3. 依渲染後的 HTML 與過去 review 慣例修正譯文(a051272563、a2de965df1)

實際建置兩頁並閱讀渲染後的內文、用 Playwright 截圖檢查後,修正只有在頁面上才看得出的問題:

  • ``field``\ 可以 顯示為「field可以」,改成一般空格
  • 「全域直譯器鎖(GIL) 來」改成全形括號且不留多餘空格:\ (GIL)來
  • 連結前多出的空格(「磁碟區上的 替代資料串流」)改用 \ 連接
  • 「錯誤代碼」→「錯誤碼」,並潤飾 match_args、frozen 兩段

再依過去 review 常見的修正項目複查:

  • \ 不放在 。 旁
  • 「串列」只用於 Python list,泛指的欄位/參數清單改為「清單」
  • token 保留英文

頁面上仍有少數英文段落:CPython 3.15 在上次同步後又修改了這些原文(例如 sentinel value → sentinel object),下次 sync 後會再標為 fuzzy。

4. 在 skills 中加入渲染後檢查與過去 review 修正清單(12ba1f9d53)

  • .scripts/render_review.py(只用標準函式庫):只建置指定的頁面,將渲染後的內文輸出到 .render-review/,並標出 role 殘留、中英間距、全形標點旁的空白、zh_CN 用語、整段英文等問題
  • 新增 review-rendered-html skill:建置頁面 → 閱讀內文 → 用 Playwright 截圖檢查排版,並附上常見渲染問題對照表
  • 新增 translate-po/references/review-corrections.md:從 150 個已合併 PR(working on ssl #763–Translate faq/design.po #1246)約 1,500 則 inline review 意見歸納出最常被要求修正的項目,附範例與 reviewer 實際要求的用詞對照表。其中 Add Translate of library/_thread.po #860 要求「打印→列印」,與 forbidden-terms.md 的「印出」衝突,本 PR 以 forbidden-terms.md 為準
  • translate-po 新增「對照過去 review 修正」與「檢查渲染頁面」兩個步驟;validate-translation、check-terminology 也加上引用

5. 修正 faq/library.po 既有條目(6190847256)

渲染檢查發現的既有問題(非 fuzzy 條目):

  • zh_CN 用語:運行→執行、聲明→宣告、設置→設為、實現→實作、鏈接→連結、獲得→取得
  • 「生成隨機數/隨機數生成器」改為「產生隨機數/隨機數產生器」,與 library/random.po 一致
  • Web Programming wiki 的連結原本用了引號而非 `文字 <url>`_,頁面上沒有變成連結,已修正
  • :ref: 章節標題與中文之間改用 \ 和「」連接;移除多餘空白並修正錯字「就可以能」

驗證方式

msgfmt -c -o /dev/null library/dataclasses.po faq/library.po
python3 .scripts/render_review.py library/dataclasses.po faq/library.po
msgattrib --only-fuzzy library/dataclasses.po faq/library.po | grep -c '^msgid'   # 0
export AGENTIC_RETRIEVAL_ENGINE=/path/to/agentic-retrieval/engine
.scripts/translation_memory.sh query "keyword-only" --top-k 5

🤖 Generated with Claude Code

josix and others added 6 commits October 25, 2026 00:14
Re-translate all fuzzy entries (94 in library/dataclasses.po, 51 in
faq/library.po) against the current msgids and drop the fuzzy flags.
Many of them were outdated machine translations that no longer matched
the source, had broken reST roles, or only covered part of the msgid.

Terminology was checked against existing translated entries with the
translation-memory lookup, e.g. 僅限關鍵字 (keyword-only), 哨兵
(sentinel), 淺複製 (shallow copy), 弱參照 (weak reference) and 互斥鎖
(mutex). "generate" is rendered as 產生 throughout dataclasses.po,
matching the dominant usage in the repo.

Only msgstr blocks changed; msgid lines are untouched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2AUU3pZYEkfs9BY3mm7bn
Add .scripts/translation_memory.sh and .scripts/translation_memory/main.py,
a stdlib-only helper that indexes this repo's .po files with
agentic-retrieval (lexical retriever, cjk tokenizer) and returns similar
already-translated entries as msgid/msgstr pairs, filtering out fuzzy and
untranslated ones. The engine is located via AGENTIC_RETRIEVAL_ENGINE or a
`retrieval` command on PATH; the helper exits 3 with a hint otherwise.

translate-po, check-terminology and validate-translation gain a lookup
step that treats these hits as reference only (glossary and README rules
still win) and skips silently when the helper is unavailable. README
documents setup and usage; CLAUDE.md gains a pointer and a corrected line
range. The index directory .agentic-retrieval/ is gitignored.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…HTML

Fix problems that only show on the built pages:
- ``field``\ 可以 rendered as "field可以"; use a normal space
- 全域直譯器鎖(GIL) used half-width parens and left a stray space; use
  \ (GIL) directly followed by the next word
- link text after 的 had an extra leading space; join it with \
- 錯誤代碼 -> 錯誤碼 (zh_CN wording)
- smoother wording for the *match_args* and *frozen* parameters

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2AUU3pZYEkfs9BY3mm7bn
Recheck the re-translated entries against the corrections reviewers most
often ask for:
- drop \  before 。 after a literal (no separator next to full-width
  punctuation)
- 串列 only for a Python list; generic lists of fields/parameters/objects
  become 清單
- keep "token" in English

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2AUU3pZYEkfs9BY3mm7bn
…kills

- .scripts/render_review.py (stdlib only): builds the given PO files'
  pages like `make build`, dumps the rendered prose to .render-review/,
  and flags rendered-only problems (leftover roles, CJK-Latin spacing,
  stray spaces around full-width punctuation, zh_CN wording, English
  paragraphs)
- new review-rendered-html skill: build, read the text dump as a reader,
  and inspect Playwright screenshots of the changed sections; includes a
  table of common rendered-only problems and fixes
- translate-po/references/review-corrections.md: what reviewers most often
  correct, mined from ~1,500 inline review comments in 150 merged PRs
  (python#763-python#1246), with examples and a table of reviewer-enforced terms
- translate-po gains a past-review checklist step and a rendered-page step;
  validate-translation and check-terminology reference both; CLAUDE.md
  points to the new script; .gitignore covers the review output dirs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2AUU3pZYEkfs9BY3mm7bn
Found by the rendered-HTML review of faq/library:
- 運行 -> 執行, 聲明 -> 宣告, 設置 -> 設為, 實現 -> 實作, 鏈接 -> 連結,
  獲得 -> 取得
- 生成 -> 產生 for random numbers, matching library/random.po
  (隨機數產生器)
- restore the Web Programming wiki link, which used quotes instead of
  `text <url>`_ and did not render as a link
- join the :ref: chapter titles to the surrounding Chinese with \  and
  「」; drop a stray space and fix the typo 就可以能
- review-rendered-html: bump a query string when re-screenshotting so the
  browser does not show a cached page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2AUU3pZYEkfs9BY3mm7bn

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant